/
/ $Header: rdbms/demo/aqmonitorREADME.txt /main/3 2010/08/13 10:44:26 xingjin Exp $
/
/ aqmonitorREADME.txt
/
/ Copyright (c) 2009, Oracle. All Rights Reserved.
/
/   NAME
/     aqmonitorREADME.txt - AQ monitor README
/
/   DESCRIPTION
/     README for AQ performance monitor
/
/   NOTES
/     See http://dbdev.us.oracle.com/twiki/bin/view/Main/AQPerformanceMonitor
/     for most recent update.
/
/   MODIFIED   (MM/DD/YY)
/   xingjin     11/05/09 - Creation
/


The following files are used for AQ performance monitor demo:
  
  aqmonitorREADME.txt   - Document for dbms_aq_monitor package

  aqmonitor.sql         - Define header and body of dbms_aq_monitor package

  aqmonitor.plot        - Plot figures based on monitoring reports 
                          (require gnuplot to be installed)

  aqmonitordemo1.sql    - Demonstrate the use of dbms_aq_monitor package 

  aqmonitoroutput1.log  - Example log output of a summary report
                          (renamed from aqmon_report.log)

  aqmonitoroutput2.log  - Example log output of detailed report for 
                          a persistent queue 
                          (renamed from aqmon_queue_1_62704.log)

  aqmonitoroutput3.png  - Example plotting result of aqmonitor.plot
                          (renamed from 
                           aqmon_queue_1_62704.11.2.persistent.gnuplot.png)


-----------------------------------------------------------------------------


1. Overview

1.1 Target

Monitor queue performance and provide statistics on queue operations. 
Help analyze system bottlenecks and provide tuning advice.

1.2 Motivation

We encounter tuning/reporting problems from customers, for example:

    * AQ queries/operations or AQ background processes becomes more 
      expensive over time. Request for a tuning remedy, as well as 
      insight about the problem.
    * Unable to scale up performance or unable to meet peak performance 
      numbers. Requests for recommendations on how to modify setup to 
      reach performance goal.
    * Best-practices for tuning/improving and existing AQ setup.
    * RAC performance problems 

We ourselves are also trying to monitor queue operations to improve 
the queue design and implementation.

1.3 System Overview

We define PL/SQL package dbms_aq_monitor to monitor AQ queues performance 
in a certain time duration. A user could set a starting time point and a 
stopping time point. The monitor could monitor specified queues between 
the time points. The monitor may generate three types of reports:

(a) A summary report for all queues: The report will display all queue 
    configuration information (such as queue id, queue owner, etc.). It 
    also gives a performance summary for each queue, and sorts queues 
    with different metrics (e.g., enqueue rate and dequeue rate).

(b) A detailed report for a certain queue: The report will show the 
    performance of the queue in a time-series manner. It also gives 
    information of other components related to the queue, such as QMN 
    cache and subscribers. Furthermore, it shows top SQL commands and 
    segments related to the queue.

(c) A report for subscription/registration statistics: The report will 
    show subscription/registration statistics in a time-series manner.

2. Users' Guide : How to Use the Monitor?

2.1 Read Before Running

2.1.1 Use add_queue_owner to add one or multiple queue owners to the 
      monitoring list. The monitor will monitor queues belonging to 
      these queue owners.

2.1.2 Use set_log_dir to set a directory for dumping log files. You need 
      to have read and write privileges to the directory. If not set, the 
      default log directory is /tmp.

2.1.3 Rules and Restrictions

(a) Queue owner must be added before the monitor is started. Otherwise 
    statistics for new owners will not be collected.

(b) Once a monitor is started, all previously collected statistics will 
    be cleared. When the monitor is stopped, collected statistics will 
    not be cleared.

(c) At most one monitor instance is allowed at all time. It means that, 
    if start_monitor procedure is successfully executed (in any session), 
    a new monitor will be started and all previous monitoring results 
    will be cleared.

(d) The monitor instance works across multiple sessions. For example, you 
    could start the monitor in one session, and stop it in another session. 
    A monitor operation can be executed in any session and will have the 
    same effect.

(e) Reports could be generated without stopping the monitor. Generating 
    reports doesn't affect ongoing monitoring.

(f) It supports Oracle Database version 10.2/11.1/11.2

2.2 Use of Package APIs

APIs in the package can be divided into several categories.

2.2.1 Set/get Monitor Configuration Parameters

  (a)
  PROCEDURE  : add_queue_owner(owner_name IN VARCHAR2 DEFAULT NULL);
  DESCRIPTION: Add a queue owner to the monitoring list. The owner name will 
               be automatically capitalized. All queues belonging to that 
               owner will be monitored.

  (b) 
  PROCEDURE  : remove_queue_owner(owner_name IN VARCHAR2 DEFAULT NULL);
  DESCRIPTION: Remove a queue owner from the monitoring list. The owner name 
               will be automatically capitalized.

  (c)
  PROCEDURE  : set_log_dir(dir_name       IN VARCHAR2 DEFAULT NULL, 
                           overwrite_file IN BOOLEAN DEFAULT FALSE);
  DESCRIPTION: Set directory for dumping log files.
  PARAM      : overwrite_file - whether to overwrite existing file if log 
                                file 'aqmon_report.log' already exists in 
                                the log directory.

  (d)
  PROCEDURE  : set_monitoring_param(param_name  IN VARCHAR2 DEFAULT NULL, 
                                    param_value IN PLS_INTEGER DEFAULT NULL);
  DESCRIPTION: Set monitoring parameters
  PARAM      : A list of param_names is as follows.

     Param Name            Default Value    Usage
     --------------------------------------------------------------------------
     CONFIG_COLLECT_FREQ   Infinity(queue   frequency for collecting
                           configuration    queue configuration info
                           info is taken
                           only at the 
                           monitor
                           starting time)
     RUNTIME_COLLECT_FREQ  60(seconds)      frequency for collecting 
                                            queue runtime stats
     AWR_DUMP_FREQ         300(seconds)     frequency for generating AWR 
                                            report
     ACCUM_DUMP_FREQ       300(seconds)     frequency for dumping 
                                            accumulative stats in log file
     FILE_PLOT             0                whether dump per-queue stats file
                                            for gnuplot. Value could be 0 or 1.
     SHARED_SUBSQL_LENGTH  150  
     SHARED_MEMEORY_BOUND  1 (MByte)        The monitor will display SQLs that
                                            are similar (i.e., their share the
                                            same first $SHARED_SUBSQL_LENGTH$
                                            characters) and in total consume 
                                            more than $SHARED_MEMORY_BOUND$ 
                                            MBytes memory

  (e)
  PROCEDURE  : show_config;    
  DESCRIPTION: Display monitor configuration parameters.

2.2.2 Monitor Operations

  (a)
  PROCEDURE  : start_monitor(start_time IN NUMBER DEFAULT 0);
  DESCRIPTION: Start the monitor. When started, the monitor will clear up 
               all previously collected statistics. It will also overwrite 
               log files in the log directory. 
  PARAM      : start_time - number of minutes after which the monitor will 
                            be started 
  
  (b)
  PROCEDURE  : stop_monitor(stop_time IN NUMBER DEFAULT 0); 
  DESCRIPTION: Stop all statistics collecting processes. Existing statistics 
               are still kept in database. The monitor will not stop until 
               this procedure is executed. 
  PARAM      : stop_time - number of minutes after which the monitor will 
                           be stopped

  (c)
  PROCEDURE  : destroy_monitor;
  DESCRIPTION: Clear all tables and data used by the monitor.

  (d)
  PROCEDURE  : clear_scheduled_job(job_name IN VARCHAR2 DEFAULT NULL); 
  DESCRIPTION: Clear scheduled job. There are two types of scheduled jobs, 
               'start_monitor' or 'stop_monitor'. Each type of job could be 
               scheduled only once. If you want to re-schedule the job at a 
               different time, you need to first clear the job and then 
               re-execute the operation.
  PARAM      : job_name - could be 'start_monitor' or 'stop_monitor'

  (e)
  PROCEDURE  : get_report(final_collect IN BOOLEAN DEFAULT TRUE);
  DESCRIPTION: Generate a summary monitoring report for all queues on all 
               instances. The report file is named 'aqmon_report.log', in 
               the log directory. 
  PARAM      : final_collect - whether collect one snapshot before generating 
                               report (only effective when the monitor is 
                               still running)

  (f) 
  PROCEDURE  : get_queue_report(queue_id       IN NUMBER DEFAULT NULL, 
                                inst_number    IN NUMBER DEFAULT NULL, 
                                final_collect  IN BOOLEAN DEFAULT TRUE,
                                single_logfile IN BOOLEAN DEFAULT FALSE);
  DESCRIPTION: Generate a detailed report for a specific queue on a specific 
               instance. 
  PARAM      : inst_number - If inst_number is not specified (i.e., 
                             inst_number IS NULL), then automatically fetch 
                             the current instance number.
                             If inst_number = -1, then generate reports for 
                             the queue on all instances.
                             For other cases, inst_number should be >= 0.
                             In Oracle database 10.2, inst_number cannot be -1.
               final_collect - whether collect one snapshot before generating 
                               report (only effective when the monitor is 
                               still running).
               single_logfile - If set to true, then all output will be 
                                written to a single logfile 
                                'aqmon_all_queues.log'. 
                                Otherwise, each queue will have its own log 
                                file. The file is named 
                                'aqmon_queue_ABC_XXYY.log', in the log 
                                directory, where ABC is the instance number 
                                and XXYY is the queue id. Note that the 
                                'aqmon_report.log' file contains all queue 
                                ids information.

  (g)
  PROCEDURE  : get_all_queues_reports(inst_number    IN NUMBER DEFAULT NULL, 
                                      final_collect  IN BOOLEAN DEFAULT TRUE,
                                      single_logfile IN BOOLEAN DEFAULT FALSE);
  DESCRIPTION: Generate a detailed report for each of the monitored queues on 
               the specified instance. Each report name follows that in 
               procedure get_queue_report. 
  PARAM      : inst_number - If inst_number is not specified (i.e., 
                             inst_number IS NULL), then automatically fetch 
                             the current instance number.
                             If inst_number = -1, then generate reports for 
                             all instances. 
                             For other cases, inst_number should be >= 0.
                             In Oracle database 10.2, inst_number cannot be -1.
               final_collect - whether collect one snapshot before generating 
                               report (only effective when the monitor is 
                               still running)
               single_logfile - If set to true, then all output will be 
                                written to a single logfile 
                                'aqmon_all_queues.log'. 
                                Otherwise, each queue will have its own log 
                                file. 

  (h)
  PROCEDURE  : get_subreg_report(final_collect  IN BOOLEAN DEFAULT TRUE);
  DESCRIPTION: Generate a report for subscription and registration statistics.
               The report file is named 'aqmon_subreg.log', in the log 
               directory. 
               This procedure is valid only for Oracle Database version 11.1 
               or 11.2. 
  PARAM      : final_collect - whether collect one snapshot before generating 
                               report (only effective when the monitor is 
                               still running)


2.2.3 Plot Data
How to plot monitoring results?

Step 1. SQL > exec dbms_aq_monitor.set_monitoring_param('file_plot', 1);

        Then, for each of the queues that detailed queue reports are 
        generated, there is an additional data file. The data file is 
        named as 'aqmon_queue_ABC_XXYY.S.T.gnuplot', where ABC stands for 
        the instance number, XXYY stands for the queue id, S could be '11.1' 
        or '11.2' (depending on the connected database version), and T could 
        be 'persistent' or 'buffered' (depending on the queue type).

Step 2. We provide a shell script 'aqmonitor.plot' to plot monitoring results 
        based on above data files. Put all the data files into the directory 
        which contains the shell script, and then run the shell script. The 
        script will generate one plot file for each of the data files. The 
        name of a plot file is the name of the corresponding data file 
        appended by '.png'.

2.3 An Example

Step 1. Connect to the database and load the monitor script. The script will 
        set up a monitor user and load the monitor package. Connect as the 
        monitor user.

Step 2. Add queue owners to the monitoring list and start the monitor.

    * SQL> set serveroutput on
    * SQL> exec dbms_aq_monitor.add_queue_owners('NIKEPLUS');
    * SQL> exec dbms_aq_monitor.start_monitor 

This immediately starts the monitor in the background, which monitors all 
queues belonging to NIKEPLUS.

You may also set monitoring parameters before starting the monitor. For 
example, if you are going to run the monitor for several days, you could 
set relatively large frequency values.

    * SQL> EXEC dbms_aq_monitor.set_log_dir('/home/jerry/test', TRUE);
    * SQL> EXEC dbms_aq_monitor.set_monitoring_param('config_collect_freq',
                                                      3600);
    * SQL> EXEC dbms_aq_monitor.set_monitoring_param('runtime_collect_freq',
                                                      600);
    * SQL> EXEC dbms_aq_monitor.set_monitoring_param('awr_dump_freq', 3000);
    * SQL> EXEC dbms_aq_monitor.set_monitoring_param('accum_dump_freq', 1800);
    * SQL> EXEC dbms_aq_monitor.add_queue_owner('NIKEPLUS');
    * SQL> EXEC dbms_aq_monitor.show_config; 

Following the above parameters,the monitor sets log directory to 
/home/jerry/test. If the directory contains old log files, the monitor
will overwrite them. The monitor will collect runtime statistics every 
600 seconds and queue configuration statistics every 3600 seconds. It 
will also dump an AWR report every 3000 seconds, and dump accumulative 
statistics in log files every 1800 seconds.

Step 3. Estimate enqueute/dequeue end time, say, one hour. Run

    * SQL > exec dbms_aq_monitor.stop_monitor(60); 

The monitor will be automatically stopped after 60 minutes.

Alternatively, you could run "exec dbms_aq_monitor.stop_monitor" at any 
time when you want to stop the monitor.

Step 4. Conduct enqueue or dequeue operations as normal.

Step 5. At any time after the monitor has been started, you could run the 
following commands to generate reports. You do not need to stop the monitor 
in order to generate reports.

    * SQL> exec dbms_aq_monitor.get_report;
    * SQL> exec dbms_aq_monitor.get_all_queues_reports; 

The above commands generate the summary report for all queues, and generate 
detailed reports for all queues on the current instance. 
